% Out.tex copyright 1992 Victor Eijkhout
%
\Chapter[chap:output] output

Every page is formatted according to a `page grid' consisting of
three elements:

\Enumerate \item the page head, this is everything that's over the
running text;
\item the page foot, this is everything that is below the running
text;
\item the running text. \TeX\ acts as if text is on a long scroll,
and the running text part of a page is simply a portion cut off from
this scroll.\>
Either or both of the head and foot of the page can be empty, but
usually one of the two contains a page number.

\OutExample
\OptionsMacro:ManPageSize=raggedbottom:10pt topskip:12pt
 height:page=3cm width:page=5cm Stop
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text textband:stop
 pagerule band:start PageCounter band:stop Stop
\TestPage 
This page does not contain much special.\EjectPage
This page is hardly better.
\OutExampleStop

This example illustrates how you first define a page grid by
\refcs{DefinePageGrid}, and then activate it by calling its name. That
last action is in fact not necessary: each definition of a page grid
automatically installs that grid as the current one.

\Section Page dimensions

Most of the time it is easiest to specify the total height of a page,
that is, including head and bottom, but sometimes it is more
convenient to specify the height of the text, and let the head and
foot simply go over and under that.

In the first case you can give the command \refcs{Height} with
two parameters:
\Ver>\Height:Page=23.5cm<Rev or inside a page grid definition the
option \refopt{height}\n{:page=...}.

In the second case you can give the command
\Ver>\Height:Text=19.55cm<Rev or inside a page grid definition the
option \opt{height:text=...}.

In page grid definitions there is the additional option
\opt{height:lines=23}.

The \cs{Height} command cannot be used in a page grid definition.

\Section Positioning the page on the paper

If your printer driver is up to specs (and you have not done any
creative macro writing) it should have the upper left corner of the
text landing at $2.54$cm from the top and left side of the paper.
If the result is not to your liking, you can shift the page by
\Ver>\Distance:hoffset= ...
\Distance:voffset= ...<Rev
These offset parameters are zero ordinarily, and they indicate the
extra shift added to the customary $2.54$cm in horizontal and
vertical direction.
 
\Section Page head, foot, text

Somewhere in the page grid the option \refopt{text} has to appear. This
option has to be inside a \refopt{textband}:
\Ver>    textband:start text textband:stop<Rev
This is not a case of overspecification, because inside a textband
the text option can appear more than once. In this manner a multicolumn
page grid can be specified.

\def\sometext{Just a bit of words, words. }
\edef\sometext{\sometext\sometext\sometext}
\edef\sometext{\sometext\sometext\sometext\sometext}
\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text hwhite:3mm text textband:stop
 pagerule band:start PageCounter band:stop Stop
\FlushRight:no \sometext
\OutExampleStop

Next to the option \opt{textband} there is \refopt{band}.
Both are ways of
creating a page wide band. The option \opt{band} is used for all
material that is not a text column, for instance footers, as in the
above examples.

The option \opt{band} can have one unusual parameter: \n{invisible}.
This makes the band act as if it has zero height or width, depending
on whether it is below or above the text, respectively.

\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text hwhite:3mm text textband:stop
 pagerule 
 band:invisible block:start Style:bold PageCounter Spaces:2
     stickout:left band:stop Stop
\FlushRight:no \sometext
\OutExampleStop
 
\SubSection More about text bands

The text band is that part of the page that has the text in it. You can
also put other material in it, such as rules or white space.

\OutExample 
\DefinePageGrid:TestPage macro:ManPageSize pagerule 
 textband:start vrule white:3pt text white:3pt vrule textband:stop 
 pagerule band:start white:fillup PageCounter band:stop Stop
\TestPage This page contains some text, a bit more text,
and even more than that. In all still just a few lines.\EjectPage
This page contains more text, still more text, and still more. 
\OutExampleStop

In the previous example the width of the page was specified.
If we only give the width of the text, the page width is calculated
dynamically. 

\OutExample 
\DefinePageGrid:TestPage macro:ManPageSize
 textband:start vrule white:3pt text white:3pt vrule textband:stop
 pagerule band:start white:fillup PageCounter band:stop Stop
\noindent This page contains some text, a bit more text,
and even more than that. In all still just a few lines.\EjectPage
This page contains more text, still more text, and still more. 
\OutExampleStop

Note how the \refopt{pagerule} and \opt{band} objects stretch
with the page.


\SubSection Topskip

In between the page head and the text is some white space, the
topskip, with special properties. The topskip is defined from the
bottom of the head to the bottom of the first line of the text. If
the height of this first line varies from page to page the topskip
acts as a buffer, keeping the bottom-to-bottom distance constant.

Topskip is set by the option \refopt{topskip}, for example
\Ver>    topskip:25pt<Rev
but if this option is left out, the page grid uses the value of
\cs{topskip} that was current at the time of the definition.
Unfortunately there is no way to change this value after the definition.

\Section The page number

The page number behaves as if it had been defined by
\Ver>\NewCounter:Page
\CounterRepresentation:Page=1<Rev
Thus you can use any command from section~\ref[sec:counters] on it.
For instance, you can have page numbers in roman numerals by 
specifying
\Ver>\CounterRepresentation:Page=I<Rev

The page number is typically used as the option \refopt{PageCounter},
but for some applications the corresponding command \refcs{PageCounter}
can be used.

\Section[sec:page:tests] Page tests

The page grid definition can set/query several properties of the
page. The following tests have been provided (see
section~\ref[sec:tests] for tests):
\Ver>\DefineTest:IsRightPage
\DefineTest:IsLeftPage
\DefineTest:FirstPage
\DefineTest:LastPage
\DefineTest:FlushBottom<Rev
\Itemize\item The tests for left/right pages are done by
 testing whether the page number of odd or even.
\item The first/last page tests can be used either for the whole
document, or for a file that's loaded as an \cs{InputFile}.
\item The first page test doesn't work at present.
\>

\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule
 band:start ifIsLeftPage else hwhite:fillup fi PageCounter 
     band:stop Stop 
This is a left hand page. \EjectPage 
This page is on the right side of a spread. 
\OutExampleStop

\Section Running heads / footers

Above it was explained how pages can be given a head and foot part.
Quite often you want changing information in such parts, for instance
the head of a left page often contains the number or title of section
that was current when that page started; the head of a right page
often contains the number or title of the section that was current
when that page ended.

In \Lollipop\ all constructs that have a title or a counter can have
that information referenced in page grids.
\Description\item \refcs{FirstPlaced}:SectionTitle
Take the title of the first section that started on this page, or
the last one that started before this page if no section started on
this page.\item \refcs{LastPlaced}:SubSectionCounter
Take the title of the last subsection that started on this page, or
the last one that started before this page if no subsection started
on this pgae.\item \refcs{PreviousPlaced}:SectionCounter
Take the counter value of the last section that started before this
page.\>

\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule 
 band:start Style:italic FirstPlaced:HeadTitle
            white:fillup PageCounter band:stop Stop
\DefineHeading:TestHeading Style:bold 
 line:start TestHeadingCounter Spaces:2 title line:stop Stop
\TestHeading A first section\par And some text.\EjectPage
This page contains text. \TestHeading A second Section\par
And more text.
\OutExampleStop

The commands \cs{FirstPlaced} and \cs{PreviousPlaced} are typically
used on left pages; \cs{LastPlaced} is more common on right pages.
You can test on what sort of page you are; see
section~\ref[sec:page:tests].

\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule 
 band:start Style:italic 
     ifIsLeftPage FirstPlaced:HeadTitle white:fillup fi
     PageCounter
     ifIsRightPage white:fillup LastPlaced:HeadTitle fi
     band:stop Stop
\DefineHeading:TestHeading Style:bold 
 line:start TestHeadingCounter Spaces:2 title line:stop Stop
\TestHeading A first section\par And some text.
\TestHeading Second section\par More text.\EjectPage
\TestHeading Third section\par Is on the right page.
\TestHeading Fourth section\par Concludes this page.
\OutExampleStop

\ImpNote 

\iSection Marks

All constructs that can have marks add their mark
items to a globally maintained list:
\Ver>\newtoks\mark@items<Rev

Only headings and page grids can have marks. Hence by default
mark generation is switched off.
\Ver>\newif\ifhas@marks
\add@generic@default{\has@marksno}<Rev

At the moment all counters and titles wind up in the mark structure:
\Ver>\def\install@counter#1{ ...
    \xp\add@mark@item\xp{\@name Counter} ... }
\add@generic@stop@default
   {\ifhas@title\xp\add@mark@item\xp{\@name Title}\fi}<Rev

The test whether the object currently being defined has marks
is performed by \cs{add@mark@item}:
\Ver>\def\add@mark@item#1{\ifhas@marks
    \csarg\newtoks{mark@toks@#1}%
    \Tmessage[mark]{Adding mark item #1}%
    \global\mark@items\xp{\the\mark@items{#1}}\fi}<Rev

This routine allocates a token list per mark item. For instance,
for a \cs{SectionTitle} a \cs{mark@toks@SectionTitle} will be allocated.
Every time a \cs{Section} occurs, a call
\Ver>\refresh@mark@item{SectionTitle}{the title}<Rev
will then be made. This merely refreshes the contents of the
specific token list:
\Ver>\def\refresh@mark@item#1#2%
   {\csarg\global{mark@toks@#1}{#2}}<Rev

Also, a call to \cs{place@mark} will be made, which puts a mark
on the current page, containing a list of item name~/ item value
pairs. This proceeds fully by expansion.
\Ver>\def\get@mark@items#1{\if\EqualStringX{#1}{SM}%
    \else{#1}{\csarg\the{mark@toks@#1}}%
         \xp\get@mark@items
    \fi}
\def\place@mark
   {\mark{\xp\get@mark@items\the\mark@items{SM}}}<Rev

Retrieving information out of a mark consists of traversing the list
of pairs, and taking the value of the keyword requested.
Thus you can call \cs{FirstPlaced:SectionTitle}.
\Ver>\def\FirstPlaced:#1 
   {\Tmessage[mark]{First Placed #1 from \firstmark}%
    \xp\get@placed\xp{\firstmark}{#1}}<Rev
The \cs{PreviousPlaced} and \cs{LastPlaced} commands are analogous,
but based on the \cs{topmark} and \cs{botmark}.

Again, everything here proceeds by expansion only, so the
string tester will consume some processor power.
\Ver>\def\get@placed#1#2{\get@@placed{#2}#1{SM}{}$}% SM: StopMarker
\def\get@@placed#1#2#3{\if\EqualStringX{#2}{SM}%
         \xp\take@to@dollar
    \else\if\EqualStringX{#1}{#2}%
              \maybe@uppercase{#3}%
              \xp\xp\xp\take@to@dollar
         \else\xp\xp\xp\get@@placed\fi
    \fi{#1}}<Rev

\ImpNoteStop

\Section Alternating page grids

In \Lollipop\ it is very easy to switch page grids: you simply specify
\Ver>    NextPageGrid:otherpage<Rev as one of the options in the
definition. If no next grid is indicated, the same page grid keeps
being used continuously until another page grid is activated
explicitly.

\OutExample
\DefinePageGrid:LTestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule 
 band:start Style:italic 
     FirstPlaced:HeadTitle white:fillup PageCounter 
     band:stop NextPageGrid:RTestPage Stop
\DefinePageGrid:RTestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule 
 band:start Style:italic 
     PageCounter white:fillup LastPlaced:HeadTitle
     band:stop NextPageGrid:LTestPage Stop
\DefineHeading:TestHeading Style:bold 
 line:start TestHeadingCounter Spaces:2 title line:stop Stop
\LTestPage
\TestHeading A first section\par And some text.
\TestHeading Second section\par More text.\EjectPage
\TestHeading Third section\par Is on the right page.
\TestHeading Fourth section\par Concludes this page.
\OutExampleStop

Another very useful application of this mechanism is to have a
special definition for the opening page of a chapter. This manual uses a
one-shot page grid \cs{EmptyPage} to remove the header and footer on the
title page. It installs \cs{LeftPage} as the next grid.

\Section Additional User Control

\SubSection Elementary manipulation

There are a few commands for simple page manipulation:
\Description\item \refcs{EjectPage}
The current page is filled up with white space, and
a new page is started.\item \refcs{ToRecto}
As \cs{EjectPage} but if the next page is a left page (meaning
that the page number is even) then the page number is increased by
one, so that the next page is a right hand page.\item \refcs{ToVerso}
As \cs{ToRecto}, except that the next page is a left page.
\>

Additionally, \refcs{NoPages} lets
all formatting and updating of values be performed, but
no pages are written to the dvi file;
\refcs{PagesOut}
reverts the effect of previous command. Note that \cs{NoPages} does not
incur any savings in time: full processing of the document is performed.
 
\ImpNote
 The test \cs{ifsink@pages} determines whether pages will be output
to the dvi file (if the test is false) or silently dropped (if true).
The sheet counter is only updated for pages written to the dvi file
so that it will takes consecutive values no matter if pages are sunk.
If a pages is dropped, \cs{deadcycles} is set to zero, otherwise it would
not be possible to drop more than \cs{maxdeadcycles} pages.
\ImpNoteStop

When a page is finished, the whole box is given to
\refcs{CurrentShipout}, which is by default \cs{shipout}. However, you
are free to define it otherwise. If your
\cs{CurrentShipout} does not actually ship out pages, you may want to
set \refcs{CountSheetsno} to prevent the effective page counter from
being updated.

Redefining \cs{CurrentShipout} usually goes together with
\refcs{SuspendOutput} and \refcs{ResumeOutput}. These commands
temporarily save the page number and the current state of the page.
See the definition of
\cs{OutputExample} in the appendix of this manual for an example. 

If you want to see te output routines in action, specify
\Ver>\Trace:out<Rev In addition \Ver>\Trace:mark<Rev tells you what
information is being saved for running head and foot lines.

\endinput

\ImpNote 

\iSection Initial setup of output routines

\Ver>
    \csarg\edef{\@command}{%
          \nxp\EjectPage
          \nxp\install@output@routine{\@name}%
          \global\hsize= \ifseen@text \CSname{\@name @text@width}%
                     \else \CSname{\next@page@grid @text@width}%
                     \fi
          \outer@start@commands \after@indent
          }<Rev

\Ver>
\def\install@output@routine#1{{\globaldefs\@ne
    \output=\xp{\csname#1@routine\endcsname}%
    \def\output@routine{#1}%
    \Tmessage[out]{Install output: #1 ---}%
    \@pagegrid@installedyes
    \csname#1@install@parameters\endcsname
    \edef\Next@PageGrid
        {\nxp\install@output@routine{\csname#1@Next@PageGrid\endcsname}}%
    }}<Rev


\ImpNoteStop